---
title: Treemap
---
import { PropsTable } from '@site/src/components/PropsTable'
import { sample } from '../utils/data.ts'
import { DocWrapper } from '../wrappers'

export const data = Array(100)
  .fill(0)
  .map(() => {
    const group = sample(['A', 'B', 'C'])
    return {
      group,
      subgroup: group + Math.floor(Math.random() * 3),
      value: sample([10, 20, 30]),
    }
  })

export const longLabelData = Array(100)
  .fill(0)
  .map(() => {
    const group = sample(['Q1', 'Q2', 'Q3', 'Q4'])

    return {
      group,
      subgroup: sample(['Revenue - Annual Subscription', 'Revenue - Professional Services', 'Revenue - Interest']),
      value: sample([10, 20, 30]),
    }
  })

export const groupColors = { A: '#5E96F5', B: '#AA70D8', C: '#31A96D' }

export const defaultProps = () => ({
  name: 'Treemap',
  containerName: 'SingleContainer',
  configKey: 'component',
  data,
  dataType: 'Datum',
  layers: [(d) => d.group, (d) => d.subgroup],
})

# Treemap
_Treemap_ is a visualization component that displays hierarchical data using nested rectangles. 
Each rectangle's area corresponds to a quantitative value, making it easy to compare different parts 
of a hierarchy at a glance.

## Data
_Treemap_ expects an array of generic data records, the properties of which will be used to define the _layers_. 
Each layer will contain tiles that represent their corresponding quantity in the data array.

For the following examples, assume data is of type `Datum[]`.

```ts
type Datum = {
  group: string;
  subgroup: string;
  value: number;
};
```

### Defining Layers
The `layers` property accepts an array of string accessor functions based on the `Datum` provided.
The first accessor will define the top level of the hierarchy, the second will provide the next level, and so on.

<DocWrapper {...defaultProps()} showContext='full' />

### Tile Values
By default, tile sizes are assigned based on the number of occurrences within the data array.
To override this behavior, you can provide your own `value` accessor function.

```ts
value = (d: Datum) => d.value
```

<DocWrapper
  {...defaultProps()}
  showContext='full'
  value={(d) => d.value}
/>

## Tile Appearance

### Tile Color
You can customize the colors for each tile using the `tileColor` property:

```ts
tileColor = (d: TreemapNode<Datum>) => groupColors[d.data.key]
```

<DocWrapper
  {...defaultProps()}
  tileColor={(d) => groupColors[d.data.key]}
/>

### Tile Padding
Control the spacing between tiles using the `tilePadding` property, which accepts a numeric value in pixels:

<DocWrapper
  {...defaultProps()}
  tilePadding={4}
/>

### Tile Border Radius
Add rounded corners to your tiles with the `tileBorderRadius` property:

<DocWrapper
  {...defaultProps()}
  tileBorderRadius={8}
/>

## Labels

### Label Content
Customize the text shown for each tile with `tileLabel`. It receives a `TreemapNode<Datum>` and should return a string. Default is `<key>: <value>`.

<DocWrapper
  {...defaultProps()}
  value={(d) => d.value}
  tileLabel={(d) => `${d.data.key} (${Math.round(d.value)})`}
  showContext='full'
/>

### Internal Node Labels
By default, only leaf nodes (tiles with no children) are labeled. 
Set `labelInternalNodes` to `true` and provide a `tilePaddingTop` value to show labels for parent nodes as well:

<DocWrapper
  {...defaultProps()}
  labelInternalNodes={true}
  tilePaddingTop={18}
/>

### Label Positioning
Adjust the position of labels using the `labelOffsetX` and `labelOffsetY` properties:

<DocWrapper
  {...defaultProps()}
  labelOffsetX={8}
  labelOffsetY={8}
/>

### Label Fit Mode
Control how labels fit within tiles using `labelFit`. This is applied to leaf nodes only.

Accepted values: `FitMode.Wrap` or `FitMode.Trim` (you can also pass strings `'wrap'` or `'trim'`). Default is `FitMode.Wrap`.

<DocWrapper
  {...defaultProps()}
  data={longLabelData}
  labelFit="wrap"
  showContext='full'
/>

### Label Trim Mode
When `labelFit` is set to trim, choose which part of the label to trim with `labelTrimMode`. Default is `TrimMode.Middle`.

<DocWrapper
  {...defaultProps()}
  data={longLabelData}
  labelFit="trim"
  labelTrimMode="end"
  showContext='full'
/>

### Dynamic Label Size
Enable or disable font size variation based on tile size with `enableTileLabelFontSizeVariation`, default is `true`:

<DocWrapper
  {...defaultProps()}
  enableTileLabelFontSizeVariation={false}
  tileLabelLargeFontSize={18}
/>

You can customize the font sizes used with:
- `tileLabelSmallFontSize`: Font size for small tiles (default: 8px)
- `tileLabelMediumFontSize`: Font size for medium tiles (default: 12px)
- `tileLabelLargeFontSize`: Font size for large tiles (default: 22px)

## Advanced Features

### Lightness Variance
Enable subtle lightness variation between sibling tiles to improve visual distinction:

<DocWrapper
  {...defaultProps()}
  enableLightnessVariance={true}
/>

### Click Affordance
Indicate that tiles are clickable by setting `showTileClickAffordance` to `true`:

<DocWrapper
  {...defaultProps()}
  showTileClickAffordance={true}
/>

## Layout Options

### Top Padding for Internal Nodes
Add extra space at the top of parent tiles to accommodate labels with `tilePaddingTop`:

<DocWrapper
  {...defaultProps()}
  labelInternalNodes={true}
  tilePaddingTop={20}
/>

## CSS Variables

_Treemap_ supports the following CSS variables:

```css
--vis-treemap-tile-stroke-color: #fff;
--vis-treemap-tile-stroke-width: 2px;
--vis-treemap-tile-hover-stroke-color: #fff;
--vis-treemap-tile-fill-color: #B9BEC3;
--vis-treemap-tile-background-color: #fff;
--vis-treemap-tile-cursor: default;
--vis-treemap-label-text-color: #000;
--vis-treemap-label-font-size: 12px;
--vis-treemap-label-opacity: 0.8;

/* Dark Theme */
--vis-dark-treemap-tile-stroke-color: #2c2c2c;
--vis-dark-treemap-tile-fill-color: #5b5f6d;
--vis-dark-treemap-label-text-color: #5b5f6d;
```

> **Note:**
> The label color is now controlled by the CSS variable `--vis-treemap-label-text-color` (and `--vis-dark-treemap-label-text-color` for dark theme). This makes it easy to theme the treemap labels for light and dark modes.

## Component Props

<PropsTable name='VisTreemap' />
